Repository navigation
feat: add an opt-in Node FFI PTY experiment - #1018
Open
John-David Dalton (jdalton) wants to merge 1 commit into
Open
John-David Dalton (jdalton) wants to merge 1 commit into
John-David Dalton (jdalton) wants to merge 1 commit into
Conversation
John-David Dalton (jdalton)
force-pushed
the
experiment/ffi-pty
branch
from
November 11, 2026 03:44
b3357fe to
2cbc89e
Compare
John-David Dalton (jdalton)
marked this pull request as ready for review
November 11, 2026 03:46
John-David Dalton (jdalton)
marked this pull request as draft
November 11, 2026 04:26
John-David Dalton (jdalton)
force-pushed
the
experiment/ffi-pty
branch
from
November 11, 2026 06:28
0c3653a to
192bd71
Compare
John-David Dalton (jdalton)
marked this pull request as ready for review
November 11, 2026 06:28
John-David Dalton (jdalton)
force-pushed
the
experiment/ffi-pty
branch
from
November 11, 2026 06:33
192bd71 to
61c1706
Compare
John-David Dalton (jdalton)
force-pushed
the
experiment/ffi-pty
branch
from
November 11, 2026 13:56
61c1706 to
9a355da
Compare
This was referenced Nov 11, 2026
John-David Dalton (jdalton)
changed the title
John-David Dalton (jdalton)
changed the title
Author
Author
|
My personal taste would be to use |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds an opt-in PTY backend using Node's built-in FFI. It leaves node-pty's public entry point, API, and npm package unchanged.
The package-size proposals, #1015 and #1016, both compress the
.nodeassets to address #864. #1015 keeps them together in the existing package; #1016 distributes them in platform-specific packages. This PR tests a different backend.Packaging the experiment separately, including compiled Windows x64 and ARM64 helpers, gives this size comparison:
Size measurement
Compared node-pty 1.2.0-beta.18 with all prebuilds against an archive containing the experiment scripts, README, license, minimal package manifest, and both compiled Windows helpers from CI. Launcher source is excluded; binaries are unsigned. Signing adds overhead. Sizes use decimal MB and savings are calculated before rounding.
Measured archives: 7,152,900 vs. 166,739 bytes packed; 26,907,504 vs. 415,460 bytes unpacked. This models standalone distribution; this PR's existing npm package still excludes the experiment.
Platform behavior
Windows selects the backend with
RtlGetVersionand uses a kill-on-close job to clean up the target and its descendants. Requires Node.js 26.12+ on x64 or ARM64. The API is experimental and does not fully implementIPty; credentials, pixel dimensions, bundled ConPTY options, and non-UTF-8 encodings are unsupported.Optional signed helper
With no publisher configured, Node is used without inspecting the helper. Otherwise, a bounded PE sniff requests at most 110 bytes and never reads the executable payload. A certificate header only triggers full Windows Authenticode verification and an exact publisher check.
Verified helpers stay file-locked to prevent replacement. Missing files, failed verification, or failed startup fall back to Node. CI builds unsigned helpers; this PR does not configure release signing.
Validation
The seven-platform run passed on the implementation before the final comment and test-title cleanup. The current VS Code PR check is pending.
Tests cover terminal I/O, Unicode, arguments, environment and working directory, large input/output, resize, pause/resume, signals, concurrent sessions, cleanup, process crashes, signed-helper verification, and the 110-byte PE sniff limit. The signed-helper integration test runs only on disposable GitHub-hosted Windows runners.
node --experimental-ffi experiments/ffi-pty/probe.mts node --experimental-ffi --test test/experiments/ffi-pty/*.test.mts